PATHMac OS 8 and 9 Developer Documentation > Interapplication Communication > AppleScript for Scripters >

AppleScript Language Guide

   

---

SYNTAX

error                                   ¬
    [ errorMessage ]                    ¬
    [ number errorNumber ]              ¬
    [ from offendingObject ]            ¬
    [ partial result resultList ]       ¬
    [ to expectedType ]

where

errorMessage is a string describing the error. Although this parameter is not required, you should provide descriptive expressions for errors wherever possible, and you should always provide an expression if you do not include a number parameter. If you do not include an error expression, an empty string ( "" ) is passed to the error handler.

errorNumber is the error number for the error. You do not have to include an error number, but if you do, the number must not be any of the error numbers listed in Error Numbers and Error Messages. In general, positive numbers from 500 to 10,000 do not conflict with error numbers for AppleScript, the Mac OS, or Apple events. If you do not include a number parameter, the value -2700 (unknown error) is passed to the error handler.

offendingObject is a reference to the object, if any, that caused the error. If you provide a partial reference, AppleScript completes it using the value of the default object (for example, the target of a Tell statement).

resultList applies only to commands that return results for multiple objects. If results for some, but not all, of the objects specified in the command are available, you can include them in the partial result parameter. If you do not include a partial result parameter, an empty list ({}) is passed to the error handler.

expectedType is a class identifier. If a parameter specified in the command was not of the expected class, and AppleScript was unable to coerce it to the expected class, then you can include the expected class in the to parameter.

EXAMPLES

The following example uses the Error command to resignal an error. The error handler resignals the error exactly as it was received, causing AppleScript to display an error dialog.

try
    word 5 of "one two three"
on error number errNum from badObj
    -- statements that handle the error
    error number errNum from badObj
end try

In the next example, an Error command in an error handler resignals the error, but changes the message that appears in the error dialog. It also changes the error number to 600 .

try
    word 5 of "one two three"
on error
    -- statements that determine the cause of the error
    error "There are not enough words." number 600
end try

The following example shows how to signal an error to handle bad data, and how to provide a handler that deals with other errors. The SumIntegersInList subroutine expects a list of integers. If any item in the passed list is not an integer, SumIntegersInList signals error number 750 and returns 0. The subroutine includes an error handler that displays a dialog if the error number is equal to 750; otherwise it uses the Error command to resignal the error. That allows other statements in the call chain to handle the unknown error number. If no statement handles the error, AppleScript displays an error dialog and execution stops.

on SumIntegerList from itemList
    try
        -- Initialize return value.
        set integerSum to 0
        -- Before doing sum, check that all items in list are integers.
        if ((count items in itemList) is not equal to ¬
            (count integers in itemList)) then
            -- If all items aren't integers, signal an error.
            error number 750
        end if
        -- Use a Repeat statement to sum the integers in the list.
        repeat with currentItem in itemList
            set integerSum to integerSum + currentItem as integer
        end repeat
        return integerSum -- Successful completion of subroutine.
    on error errStr number errorNumber
        -- If our own error number, warn about bad data.
        if the errorNumber is equal to 750 then
            display dialog "All items in the list must be integers."
            return integerSum -- Return the default value (0).
        else
            -- An unknown error occurred. Resignal, so the caller
            -- can handle it, or AppleScript can display the number.
            error number errorNumber
        end if
    end try
end SumIntegerList

Let's look at how the SumIntegersInList subroutine handles various error conditions.

A Successful Call

This first call completes without error.

set sumList to {1, 3, 5}
set listTotal to SumIntegerList from sumList --result: 9

A Call With Bad Data

The following call passes bad data--the list contains an item that isn't an integer.

set sumList to {1, 3, 5, "A"}
set listTotal to SumIntegerList from sumList
if listTotal is equal to 0 then
-- The subroutine didn't total the list--do something
-- to handle the error. (Not shown.)

The SumIntegerList routine checks the list and signals an error 750 because the list contains at least one non-integer item. The routine's error handler recognizes error number 750 and puts up a dialog to describe the problem. The SumIntegerList routine returns 0. The script checks the return value and, if it is equal to 0, does something to handle the error.

An Unknown Error Occurs and Is Not Handled By the Caller

Suppose some unknown error occurs while SumIntegerList is processing the integer list in the previous call. When the unknown error occurs, the SumIntegerList error handler calls the Error command to resignal the error. Since the caller doesn't handle it, AppleScript displays an error dialog and execution halts. The SumIntegerList routine does not return a value.

An Unknown Error Is Handled By the Caller

Finally, suppose the caller has its own error handler, so that if the subroutine passes on an error, the caller can handle it. Assume again that an unknown error occurs while SumIntegerList is processing the integer list.

try
    set sumList to {1, 3, 5}
    set listTotal to SumIntegerList from sumList
on error errMsg number errorNumber
    display dialog "An unknown error occurred:  " ¬
        & errorNumber as string
end try

In this case, when the unknown error occurs, the SumIntegerList error handler calls the Error command to resignal the error. Because the caller has an error handler, it is able to handle the error by displaying a dialog that includes the error number. Execution can continue if it is meaningful to do so.